<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>HTML::Merge::App::Repository - A sample of a complex application</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>

<body style="background-color: white">

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<ul>

		<li><a href="#overview">Overview</a></li>
		<li><a href="#database">Database</a></li>
		<li><a href="#the_road_ahead">The road ahead</a></li>
	</ul>

	<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>HTML::Merge::App::Repository - A sample of a complex application</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>
</p>
<h2><a name="overview">Overview</a></h2>
<p>The goal of the HTML::Merge::App::Repository is to provide a 
form builder multi language design environment. 
In order to accomplish that all form design meta data are stored 
in a databases where each record represent a form element. 
A rendering engine has been created to render the form from the database. 
The project is lacking a GUI interface for populating the form meta data database.</p>
<p>
</p>
<h2><a name="database">Database</a></h2>
<p>The entire project is stored on tables residing on HTML::Merge system database 
(tested on SQLite and MySQL). The table creation and initing code  reside 
in the class HTML::Merge::App::Repository and it is being utilize in the 
mergecreateinstance script. HTML::Merge::App::Repository also relay on 
definition stored on the tbl table populated by the 'private/sql/tbl.dat' 
pipe delimited file. This actually break the possibility of treating the 
Repository as an add-on module since it taints the mergecreateinstance 
and relay on default data from the basic system tbl table, but this 
design flows can easily be repaired.</p>
<dl>
<dt><strong><a name="item_tbl__2d_master_table">tbl - master table</a></strong>

<dt><strong><a name="item_fldtyp__2d_contains_all_form_elements_types_2e">FLDTYP - contains all form elements types.</a></strong>

<dd>
<pre>
  example of a text fields:
  
  tbl:         &quot;FLDTYP&quot;
  langug_code: &quot;&quot; - nothing, not language dependent information.
  code:        &quot;1&quot; - unique identifier.
  name:        &quot;TEXT_FIELD&quot; - widget description.
  number:      &quot;1&quot; - A boolean value indicating if this object requires 
                     a text label to accompany the widget.
  note:        &quot;&lt;input type=text #fldstatus# value=``#value#`` size=``#size#`` 
                maxlength=``#maxlength#`` @STDATR@ @STDEVNT@ #field_data#&gt;|0|&quot; 
                - this data is what the rendering engine will use to 
                create the HTML result. 
  realm_id:    &quot;&quot; - Not used.</pre>
</dd>
<dt><strong><a name="item_macros__2d_contain_macros_to_support_the_fldtyp_me">MACROS - contain macros to support the FLDTYP methodology.</a></strong>

<dd>
<pre>
  example of standard events macro:
  tbl: &quot;MACROS&quot;
  langug_code: &quot;&quot; - nothing, not language dependent information.
  code: &quot;1&quot; - unique identifier.
  name: &quot;STDATR&quot; - widget description.
  number: &quot;0&quot; - Not used.
  note: &quot;name=``#field_name#`` id=``#field_name#`` style=``width: #width#; 
        height: #height#; background-color: 
  realm_id: &quot;&quot; - Not used.</pre>
</dd>
<dt><strong><a name="item_fldsts__2d_look_up_for_the_html_3a_3amerge_3a_3aap">FLDSTS - Look up for the HTML::Merge::App::Repository field status.</a></strong>

<dd>
<pre>
      contains: 
          1 - normal
          2 - read only
          3 - disabled
          4 - hidden</pre>
</dd>
<dt><strong><a name="item_fldmtx__2d_a_per_language_matrix_for_describing_fi">FLDMTX - A per language matrix for describing field status.</a></strong>

<dt><strong><a name="item_langug__2d_all_supported_languages_and_definitions">LANGUG - All supported languages and definitions: ISO code, direction.</a></strong>

<dt><strong><a name="item_status__2d_record_state_2e">STATUS - Record state.</a></strong>

<dd>
<pre>
       contains: 
           0 - deleted
           1 - blocked
           2 - active</pre>
</dd>
<dt><strong><a name="item_frmstr__2d">FRMSTR -</a></strong>

<pre>
  Form strings, holds form elements basic text according to the selected
  system language. For instance the grid 'alt' text for sorting or the
  record left text at the grid bottom.</pre>
<dl>
<dt><strong><a name="item_templates_t__2d_system_templates_catalog">templates_t - System templates catalog</a></strong>

<dd>
<pre>
  id: Unique identifier.</pre>
</dd>
<dd>
<pre>
  templatename: The template file name relative to the template directory.</pre>
</dd>
<dd>
<pre>
  description: The template description.</pre>
</dd>
<dd>
<pre>
  tag: extra data associated with the template - never been used.</pre>
</dd>
<dd>
<pre>
  epitaph: Mark deleted templates.</pre>
</dd>
<dd>
<pre>
  instance_id: the instance id from instance_t table indicating which merge 
       instance this template belong to (in case of a multi instance environment)</pre>
</dd>
<dt><strong><a name="item_instance_t__2d_html_3a_3amerge_instances_catalog">instance_t - HTML::Merge instances catalog</a></strong>

<dd>
<pre>
  id: Unique identifier.</pre>
</dd>
<dd>
<pre>
  instancename: The instance merge.conf file path.</pre>
</dd>
<dd>
<pre>
  description: The instance description.</pre>
</dd>
<dd>
<pre>
  tag: extra data associated with the instance - never been used.</pre>
</dd>
<dd>
<pre>
  epitaph: Mark deleted instances.</pre>
</dd>
<dd>
<p>This table is managed automatically by merge.</p>
</dd>
<dt><strong><a name="item_repository_t__2d_forms_meta_repository">repository_t - forms meta repository</a></strong>

<dd>
<pre>
  rid: Unique identifier.</pre>
</dd>
<dd>
<pre>
  template_id: The specific template</pre>
</dd>
<dd>
<pre>
  field_parent_repository_id: Mark an rid value of a repository entry which it's</pre>
</dd>
<dd>
<pre>
      template_id equals zero. All of the row data is inherited to the non filled fields 
       in the current row.
  field_name: The description of the field - will be used as the HTML field id and name value.</pre>
</dd>
<dd>
<pre>
  fldtyp_code: The tbl table FLDTYP code field value.</pre>
</dd>
<dd>
<pre>
  note: A place for comments.</pre>
</dd>
<dd>
<pre>
  src: Used for widgets which have an external data source - 
       image, combo box  and data grid.</pre>
</dd>
<dd>
<pre>
  value: Used for all widget which their HTML code contain a value key.
  size:  Used for all widget which their HTML code contain a size key and also   
         for the data grid to indicate number of visible rows.
 maxlength: Used for all widget which their HTML code contain a maxlength  
         key and also for the data grid to indicate the maximum number of  
         rows fetched in a single request.</pre>
</dd>
<dd>
<pre>
 width: Used by all widgets - style sheet width.</pre>
</dd>
<dd>
<pre>
 height: Used by all widgets - style sheet width.</pre>
</dd>
<dd>
<pre>
 class: Used by all widgets - the widget encapsulating DIV class key;</pre>
</dd>
<dd>
<pre>
 fldsts_code: The tbl table field status code.</pre>
</dd>
<dd>
<pre>
 realm_id: field creation permissions based on HTML::Merge security module.</pre>
</dd>
<dd>
<pre>
 arrangement: The drawing and placement order of the widgets in the form 
      (z order).</pre>
</dd>
<dd>
<pre>
 onBlur: The content of the HTML result onBlur key.</pre>
</dd>
<dd>
<pre>
 onClick: The content of the HTML result onClick key.</pre>
</dd>
<dd>
<pre>
 onDblClick: The content of the HTML result onDblClick key.</pre>
</dd>
<dd>
<pre>
 onChange: The content of the HTML result onChange key.</pre>
</dd>
<dd>
<pre>
 onMouseOver: The content of the HTML result onMouseOver key.</pre>
</dd>
<dd>
<pre>
 onMouseMove The content of the HTML result onMouseMove key.</pre>
</dd>
<dd>
<pre>
 onMouseOut The content of the HTML result onMouseOut key.</pre>
</dd>
<dd>
<pre>
 field_data: Extra data to the HTML result which can't be
              created using the other fields. for example 
              giving class data to the widget and no the 
              encapsulating DIV.
 pos_x: The screen x position in pixels.</pre>
</dd>
<dd>
<pre>
 pos_y: The screen y position in pixels.</pre>
</dd>
<dd>
<pre>
 background: The widget background in HTML keyword or RGB notation   (#xxyyzz).</pre>
</dd>
<dd>
<pre>
 border: The encapsulating DIV border in CSS notation.</pre>
</dd>
<dd>
<pre>
 example: &quot;1px solid black&quot;.</pre>
</dd>
<dd>
<pre>
 pos_delta: The length delta in pixels of the length between the widget and it's lablel.</pre>
</dd>
<dd>
<pre>
 status_code: The tbl table code indicating the record state only value of &quot;2&quot;    
              will be drawn.</pre>
</dd>
<dt><strong><a name="item_repository_language_matrix__2d_widgets_multi_lingu">repository_language_matrix - widgets multi lingual captions</a></strong>

<dd>
<pre>
 rid: Unique identifier.</pre>
</dd>
<dd>
<pre>
 repository_id: The repository_t rid value.</pre>
</dd>
<dd>
<pre>
 langug_code: The tbl table language code value.</pre>
</dd>
<dd>
<pre>
 caption: The form caption.</pre>
</dd>
<dt><strong><a name="item_the_repository_rendering_engine">The repository rendering engine</a></strong>

<dd>
<p>The rendering engine is the template ``Repository/build_form.inc'' which is included in pages usually 
Between a form element.</p>
</dd>
<dd>
<p>The engine then:
</p>
</dd>
<dd>
<pre>

  1.Load all macros from the tbl table.</pre>
</dd>
<dd>
<pre>
  2.Invokes the template &quot;Repository/repository_query.inc&quot; - 
    which loads the specific template data from the database 
    repository_t + the field type definition from the tbl 
    table + all user_realm data curtsey's of the 
    &quot;Reposiotry/get_user_realms.inc&quot; template.</pre>
</dd>
<dd>
<pre>
  3.Replace all &quot;@&quot;  encapsulated fields in the field definition 
    with the corresponding macro. For example @STATR@.</pre>
</dd>
<dd>
<pre>
  4.Replace all &quot;#&quot;  encapsulated fields in the field definition
    with specific database value. For example #class# will be 
    replaced with the current record value of the class field.</pre>
</dd>
<dd>
<pre>
  5.Replace all &quot;``&quot; with '&quot;' to avoid placement problems.</pre>
</dd>
<dd>
<pre>
  6.Replace all '`' with &quot;'&quot; to avoid placement problems.</pre>
</dd>
<dd>
<pre>
  7.Run the result through Merge so Merge tag like RINCLUDE 
    will be translated.</pre>
</dd>
<dd>
<pre>
  8.Create two DIV elements: [field_name]_fld - which holds the widget, 
    [field_name]_cap which holds the label if needed by the widget.</pre>
</dd>
<dd>
<p>Since there is a sub form widget which let us encapsulate other forms inside the     
current form, The engine handle a stack for saving all different query engines that will    
be used in the page creation so no query data will interfere with top level queries.
This is done using the ``Repository/repush.inc'' and  ``Repsoiotry/repop.inc''            
templates.
</p>
</dd>
<dd>
<pre>

The engine uses the following RVAR as init variants:
           1.dir - The direction of the rendering. Option are &quot;rtl&quot; ( right to left) or &quot;ltr&quot; (left to right)
           2.__DEBUG__ - Paints border on all encapsulating DIV element.
           3.repository_query_engine - Specify your own query engine.
           4.repository_template - Specify the template to be rendered. Default: the current template.</pre>
</dd>
</li>
<dt><strong><a name="item_the_repository_widgets__2d_the_widget_list_based_o">The repository widgets - The widget list based on the tbl table</a></strong>

<dd>
<pre>
   1. TEXT_FIELD - HTML standard text field + corresponding caption.
   2. LABEL - A &lt;pre&gt;&lt;/pre&gt; encapsulated text.
   3. COMBO BOX - HTML standard combo box + corresponding caption. The src field
      is used to specify a template which will create (usually by  querying the db) 
      the &lt;option&gt; section of the select. 
      Source  templates are usually marked with &quot;bnd&quot; file extension.
   4. IMAGE -  HTML standard image.
   5. BUTTON - HTML standard button.
   6. CHECK_BOX - HTML standard check box + corresponding caption.
   7. RADIO - HTML standard radio button + corresponding caption.
   8. PASSWORD - HTML standard password field + corresponding caption.
   9. RECTANGLE - Used to create boxes using the border and background attribute.
      usefull for grouping elements. 
   10. GRID - A complex combination of HTML::Merge and Javascript that create a data
       grid based on an SQL query. The grid builds an array of objects called
      &quot;grid_array&quot; from the query and render itself based  on that array. 
   The grid also support triggering of events an automatic ordering of the 
   grid  by manipulating the SQL query.
     
parameters:</pre>
</dd>
<dd>
<pre>
     size - number of shown records.
                     maxlength - maximum number of record to fetch in a request.
     src - The template which needs to contain an RVAR called     
           &quot;qrid_query&quot; which holds the SQL query that the grid    
            is bases upon.
     width - specify a fix width.
     height - override the size definition and specify the grid   height in pixels.
     field_data - is used to specify in a key=value;key=vale ...
                   notation special parameters to the grid.
                   uid: the specific name of the field in the sql                
                        query which is used as a unique row identifier.
                   quote_data: boolean if true all function  returning 
                               field data will return the data quoted
                               with semicolons.
      background - The background color of the field titles.</pre>
</dd>
<dd>
<p>events: On all supported events you can specify a pointer to a Javascript
function (the name without the parameters section). when this  
function  will be invoked the grid will send an object to the
function containing three elements:</p>
</dd>
<dd>
<pre>
                      uid: The referred row uid database val.
                    rowid: The physical position of the row in the grid.
                     flag: Boolean actioned or not actioned.</pre>
</dd>
<dd>
<pre>
   onDblClick -  Triggered when double clicking the grid row (also
                 referred to as zooming) 
                 the function will be
                 invoked.</pre>
</dd>
<dd>
<pre>
   onChange - Triggered when pressing on the side control for   
              highlighting a row.</pre>
</dd>
<dd>
<pre>
   onClick - Triggered when pressing on the title for sorting (never
              been tested).</pre>
</dd>
<dd>
<p>API: The grid is a class. The automatic created instance is named as
follows: ``c_[field_name]_grid'' the following methods where design 
to help the programmer interact with the grid.</p>
</dd>
<dd>
<pre>
          Refresh(line_offset): Redraw the grid based on the &quot;grid_array&quot;
          starting from a specify line_offset First line is 1.</pre>
</dd>
<dd>
<pre>
          Rebuild(extra,obj,suppress_header_rebuild,line_offset,form):
          Rebuild the grid from the database.</pre>
</dd>
<dd>
<pre>
  extra - Name of a template the should be run before the fetching the data 
          from the database. Usually used for  doing Insert or Update.</pre>
</dd>
<dd>
<pre>
  obj - An object  containing element which should be
        passed to the extra template.</pre>
</dd>
<dd>
<pre>
  suppress_header_rebuild - don't redraw the fields title line.</pre>
</dd>
<dd>
<pre>
  line_offset - Same as in the refresh method.
  form - name of a form which can be used to transfer the  
         data to the server through. if not defined a url string  
         will be created, and the location.href method will be  
         used (limited to 255 charecters).</pre>
</dd>
<dd>
<pre>
 GetMarkedUid() - Return all highlighted rows &quot;uid&quot; as an array.
 GetMarkedUidAsStr() -  Return all highlighted rows &quot;uid&quot; as a      coma delimited row.
 GetMarkedRowid() - Return all highlighted rows &quot;rowid&quot; as an array.
 GetMarkedUidAsStr() -  Return all highlighted rows &quot;rowid&quot; as a      coma delimited row.
 GetZoomedUid() - Return zoomed row &quot;uid&quot;.
 GetZoomedRowid() - Return zoomed row &quot;rowid&quot;.
 SetHeaderCaptionByID(id) - Change the title caption.
 SetHeaderCaptionByFieldName(field_name) - Change the title       caption.
 GetHeaderCaptionByID(id) - Get the title caption.
 GetHeaderCaptionByFieldName(field_name) - Get the title       caption.
 GetFieldByRowAndCol(row,col) - Get the grid data of a specific cell.
 DelColumnByID(id) - Dells an entire column based on the id.
 DelColumnByFieldName(field_name) - Dells an entire column        based on the column        name.
 GetZoomColor() - Get the grid zoom color (the row color when       double clicking).
 SetZoomColor(color) - Set the zoom color automatically.
 GetCursorColor() - Get the grid cursor color.
 SetCursorColor(color) - Set the grid cursor color.</pre>
</dd>
<dd>
<p>Stracture: ``Repository/Grid/grid.inc'' - Basic CSS and constructor initting.</p>
</dd>
<dd>
<pre>
     &quot;Repository/Grid/grid_build_data.inc&quot; - Do the actual build of       
         the &quot;grid_array&quot; from the database.</pre>
</dd>
<dd>
<pre>
     &quot;Repository/Grid/grid_refresh.html&quot; - The request to the server 
         triggered when sorting or calling the Rebuild method.</pre>
</dd>
<dd>
<pre>
     &quot;javascript/Repository/Grid/grid.js&quot; - The grid class.
          
 11. SUMBIT - HTML standard submit button.
 12. LINE  - Create horizontal and vertical lines based on the
             pos_x,pos_y,width,height attributes
 13. TEXT - Just plain text.
 14. DATE_BOX - Not finished should open our standard date box automatically.
 15. SUB_FORM - creates a sub form which runs inside the template specified in t     the &quot;src&quot; element.</pre>
</dd>
</dl>
</dl>
<p>
</p>
<h2><a name="the_road_ahead">The road ahead</a></h2>
<p>- Add a delta_y column.</p>
<p>- Change the grid ``grid_arr'' to a faster created storage type.</p>
<p>-  Render all CSS attribute as a style sheet (INPUT:my_field). that way the code will     
be more consistent and more important it will be possible not to render empty    
attributes. and cut down the result HTML size dramatically.</p>
<p>- rewrite ``build_form.inc'' when HTML::Merge performance issues will be solved.</p>
<p>- render the result of the build_form operation so that it won't have to be rendered from   
the database everytime. Could be done inside HTML::Merge (compilation time) Or   
outside HTML::Merge by dynamically creating templates for the rendered result Or   
even compiled templates in the cache directory.</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>(c) RAZ Information Systems Ltd 1999 - 2005.</p>
<p>The HTML::Merge::App::Repository is licensed under the same terms Perl is licensed.</p>
<p>Permission is granted to copy, distribute, and/or modify this document under the</p>
<p>terms of the GNU Free Documentation License, 

</p>
<p>Version 1.1 or any later version published by the Free Software Foundation. 

</p>

</body>

</html>
